JavaScript Temporal Instant: высокоточные вычисления времени

JavaScript давно известен своими неидеальными возможностями для работы с датой и временем. Устаревший объект Date, несмотря на широкое использование, страдает от изменяемости, непоследовательного поведения API и плохой поддержки часовых поясов. Встречайте Temporal API — современный подход к манипулированию датой и временем, разработанный для устранения этих недостатков. В основе Temporal лежит объект Instant, представляющий конкретный момент времени с наносекундной точностью. Этот пост представляет собой исчерпывающее руководство по использованию Temporal.Instant для высокоточных вычислений времени в ваших JavaScript-приложениях, ориентированное на глобальную аудиторию с разнообразными потребностями.

Что такое Temporal.Instant?

Temporal.Instant представляет собой момент времени, измеряемый от эпохи Unix (1 января 1970 года, 00:00:00 по всемирному координированному времени (UTC)) с наносекундной точностью. В отличие от устаревшего объекта Date, Temporal.Instant неизменяем (immutable), что означает, что его значение не может быть изменено после создания. Эта неизменяемость крайне важна для предотвращения неожиданных побочных эффектов и обеспечения целостности данных, особенно в сложных приложениях.

Создание объектов Temporal.Instant

Существует несколько способов создания объектов Temporal.Instant:

1. Из числа (миллисекунды с начала эпохи)

Вы можете создать Instant из количества миллисекунд, прошедших с начала эпохи Unix. Это похоже на то, как работает устаревший объект Date, но Temporal.Instant предлагает большую точность.

            
const instant = Temporal.Instant.fromEpochMilliseconds(1678886400000); // March 15, 2023, 00:00:00 UTC
console.log(instant.toString()); // Output: 2023-03-15T00:00:00Z

            

              
                Copy
              
            
          

2. Из числа (наносекунды с начала эпохи)

Для еще более высокой точности вы можете создать Instant из количества наносекунд, прошедших с начала эпохи Unix. Это самый точный способ представления момента времени с помощью Temporal.Instant.

            
const instant = Temporal.Instant.fromEpochNanoseconds(1678886400000000000n); // March 15, 2023, 00:00:00 UTC
console.log(instant.toString()); // Output: 2023-03-15T00:00:00Z

            

              
                Copy
              
            
          

Обратите внимание на использование суффикса n для обозначения литерала BigInt. Значения в наносекундах часто превышают максимально безопасное целое число для JavaScript, поэтому использование BigInt необходимо для сохранения точности.

3. Из строки формата ISO 8601

Temporal.Instant также можно создать из строки формата ISO 8601, представляющей дату и время в UTC.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
console.log(instant.toString()); // Output: 2023-03-15T00:00:00Z

const instantWithFractionalSeconds = Temporal.Instant.from('2023-03-15T00:00:00.123456789Z');
console.log(instantWithFractionalSeconds.toString()); // Output: 2023-03-15T00:00:00.123456789Z

            

              
                Copy
              
            
          

Строка ISO 8601 должна заканчиваться символом Z для обозначения UTC. Строка может опционально включать доли секунды с точностью до девяти цифр.

4. Из Temporal.Now (системные часы)

Вы можете получить текущий момент времени, используя Temporal.Now.instant():

            
const now = Temporal.Now.instant();
console.log(now.toString()); // Output: Varies depending on the current time

            

              
                Copy
              
            
          

Работа с объектами Temporal.Instant

После того как у вас есть объект Temporal.Instant, вы можете выполнять с ним различные операции. Помните, что объекты Temporal.Instant неизменяемы, поэтому эти операции возвращают новые объекты Temporal.Instant, а не изменяют исходный.

1. Сложение и вычитание времени

Вы можете добавлять или вычитать время из Instant с помощью методов add() и subtract(). Эти методы принимают объект Temporal.Duration, который представляет собой промежуток времени.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const duration = Temporal.Duration.from({ hours: 2, minutes: 30 });

const futureInstant = instant.add(duration);
console.log(futureInstant.toString()); // Output: 2023-03-15T02:30:00Z

const pastInstant = instant.subtract(duration);
console.log(pastInstant.toString()); // Output: 2023-03-14T21:30:00Z

            

              
                Copy
              
            
          

Вы также можете использовать строковое представление для продолжительности:

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const futureInstant = instant.add('PT2H30M'); // ISO 8601 duration string
console.log(futureInstant.toString()); // Output: 2023-03-15T02:30:00Z

            

              
                Copy
              
            
          

2. Сравнение моментов времени

Вы можете сравнить два объекта Temporal.Instant с помощью метода compare(). Этот метод возвращает:

• -1, если первый момент времени раньше второго.
• 0, если два момента времени равны.
• 1, если первый момент времени позже второго.

            
const instant1 = Temporal.Instant.from('2023-03-15T00:00:00Z');
const instant2 = Temporal.Instant.from('2023-03-15T01:00:00Z');

console.log(Temporal.Instant.compare(instant1, instant2)); // Output: -1
console.log(Temporal.Instant.compare(instant2, instant1)); // Output: 1
console.log(Temporal.Instant.compare(instant1, instant1)); // Output: 0

            

              
                Copy
              
            
          

3. Преобразование в другие типы Temporal

Temporal.Instant можно преобразовать в другие типы Temporal, такие как Temporal.ZonedDateTime, Temporal.PlainDateTime и Temporal.PlainDate. Это необходимо для работы с часовыми поясами и локализованными представлениями даты и времени.

а. В Temporal.ZonedDateTime

Temporal.ZonedDateTime представляет дату и время с указанием конкретного часового пояса. Чтобы преобразовать Instant в ZonedDateTime, необходимо указать часовой пояс.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const zonedDateTime = instant.toZonedDateTimeISO('America/Los_Angeles');
console.log(zonedDateTime.toString()); // Output: 2023-03-14T17:00:00-07:00[America/Los_Angeles]

            

              
                Copy
              
            
          

Метод toZonedDateTimeISO() создает ZonedDateTime, используя календарь ISO 8601. Вы также можете использовать toZonedDateTime() для указания другого календаря.

б. В Temporal.PlainDateTime

Temporal.PlainDateTime представляет дату и время без часового пояса. Чтобы преобразовать Instant в PlainDateTime, сначала нужно преобразовать его в ZonedDateTime, а затем получить из него PlainDateTime.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const zonedDateTime = instant.toZonedDateTimeISO('America/Los_Angeles');
const plainDateTime = zonedDateTime.toPlainDateTime();
console.log(plainDateTime.toString()); // Output: 2023-03-14T17:00:00

            

              
                Copy
              
            
          

в. В Temporal.PlainDate

Temporal.PlainDate представляет дату без времени или часового пояса. Аналогично PlainDateTime, сначала вы преобразуете его в ZonedDateTime.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const zonedDateTime = instant.toZonedDateTimeISO('America/Los_Angeles');
const plainDate = zonedDateTime.toPlainDate();
console.log(plainDate.toString()); // Output: 2023-03-14

            

              
                Copy
              
            
          

4. Получение миллисекунд и наносекунд с начала эпохи

Вы можете получить количество миллисекунд или наносекунд, прошедших с начала эпохи Unix, используя свойства epochMilliseconds и epochNanoseconds соответственно.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00.123456789Z');
console.log(instant.epochMilliseconds); // Output: 1678886400123
console.log(instant.epochNanoseconds); // Output: 1678886400123456789n

            

              
                Copy
              
            
          

Сценарии использования Temporal.Instant

Temporal.Instant особенно полезен в сценариях, где требуются высокоточные вычисления времени. Вот несколько примеров:

1. Логирование событий и аудит

При логировании событий или аудите системной активности крайне важно зафиксировать точное время, когда произошло событие. Temporal.Instant обеспечивает необходимую точность для корректной записи временных меток.

            
function logEvent(eventDescription) {
  const timestamp = Temporal.Now.instant().toString();
  console.log(`[${timestamp}] ${eventDescription}`);
}

logEvent('User logged in');
logEvent('File saved');

            

              
                Copy
              
            
          

2. Измерение производительности

Измерение производительности кода требует точного хронометража. Temporal.Instant можно использовать для измерения времени выполнения блоков кода с наносекундной точностью.

            
const start = Temporal.Now.instant();
// Code to measure
for (let i = 0; i < 1000000; i++) {
  // Some operation
}
const end = Temporal.Now.instant();

const duration = end.since(start);
console.log(`Execution time: ${duration.total('milliseconds')} milliseconds`);

            

              
                Copy
              
            
          

3. Распределенные системы и синхронизация данных

В распределенных системах поддержание согласованности данных между несколькими узлами часто требует точной временной синхронизации. Temporal.Instant можно использовать для представления временных меток обновлений данных и разрешения конфликтов на основе времени.

Например, рассмотрим сценарий, в котором данные реплицируются на несколько серверов в разных географических точках (например, в сети доставки контента или распределенной базе данных). Если пользователь обновляет запись, система должна обеспечить последовательное распространение последнего обновления на все серверы. Использование Temporal.Instant для отметки времени каждого обновления обеспечивает точное упорядочивание, даже при наличии сетевой задержки и возможного рассогласования часов между серверами.

4. Финансовые транзакции

Финансовые транзакции часто требуют высокоточных временных меток для соответствия нормативным требованиям и точного ведения учета. Точное время сделки, платежа или перевода должно быть записано с высокой точностью, чтобы избежать споров и обеспечить подотчетность.

Например, системы высокочастотной торговли требуют микросекундной или наносекундной точности для фиксации точного момента исполнения ордера. Даже небольшие расхождения во времени могут привести к значительным финансовым последствиям. Temporal.Instant обеспечивает разрешение, необходимое для этих критически важных приложений.

5. Научные приложения

Многие научные приложения, такие как астрономия, физическое моделирование и сбор данных с экспериментов, требуют очень точных измерений времени. Эти измерения часто имеют решающее значение для анализа данных и получения точных выводов.

Представьте себе телескоп, собирающий данные от далекой звезды. Точное время каждого наблюдения необходимо для определения положения, движения и других свойств звезды. Temporal.Instant позволяет ученым записывать эти временные метки с необходимой точностью.

Интернационализация и часовые пояса

Хотя Temporal.Instant представляет собой момент времени в UTC, важно учитывать часовые пояса при работе с датами и временем для глобальной аудитории. Как было показано ранее, вы можете преобразовать Instant в Temporal.ZonedDateTime, чтобы представить тот же момент времени в конкретном часовом поясе.

При отображении дат и времени пользователям всегда используйте их местный часовой пояс, чтобы избежать путаницы. Вы можете получить часовой пояс пользователя из его браузера или операционной системы. Например, можно использовать API Intl.DateTimeFormat для форматирования даты и времени в соответствии с локалью и часовым поясом пользователя.

            
const instant = Temporal.Instant.from('2023-03-15T00:00:00Z');
const zonedDateTime = instant.toZonedDateTimeISO(Temporal.Now.timeZone());

const formatter = new Intl.DateTimeFormat(undefined, {
  year: 'numeric',
  month: 'long',
  day: 'numeric',
  hour: 'numeric',
  minute: 'numeric',
  timeZoneName: 'short',
});

console.log(formatter.format(zonedDateTime)); // Output: Varies depending on the user's locale and time zone

            

              
                Copy
              
            
          

Этот пример использует системный часовой пояс пользователя. При необходимости вы можете заменить Temporal.Now.timeZone() на конкретный идентификатор часового пояса (например, 'America/Los_Angeles').

Примечание: Всегда помните о переходе на летнее время (DST) при работе с часовыми поясами. Правила часовых поясов могут меняться, поэтому важно использовать актуальную базу данных часовых поясов для обеспечения точных расчетов. Temporal API автоматически обрабатывает переходы на летнее время при конвертации между часовыми поясами.

Поддержка в браузерах и средах выполнения

На конец 2023 года Temporal API все еще является относительно новым и пока не полностью поддерживается во всех браузерах и средах выполнения JavaScript. Вам может потребоваться использовать полифил для обеспечения поддержки в старых браузерах.

Пакет @js-temporal/polyfill предоставляет полифил для Temporal API. Вы можете установить его с помощью npm или yarn:

            
npm install @js-temporal/polyfill

            

              
                Copy
              
            
          

Затем импортируйте полифил в свой JavaScript-код:

            
import '@js-temporal/polyfill';

            

              
                Copy
              
            
          

Это добавит Temporal API в глобальную область видимости, что позволит вам использовать его в своем коде, даже если среда выполнения не поддерживает его нативно.

Лучшие практики и рекомендации

• Используйте UTC для внутреннего хранения и вычислений: Храните все временные метки в UTC, чтобы избежать проблем, связанных с часовыми поясами. Преобразуйте в локальные часовые пояса только при отображении дат и времени пользователям.
• Осторожно обращайтесь с преобразованиями часовых поясов: Помните о DST и изменениях в правилах часовых поясов. Используйте актуальную базу данных часовых поясов для обеспечения точных преобразований.
• Используйте BigInt для наносекундных значений: Значения в наносекундах часто превышают максимально безопасное целое число для JavaScript. Используйте BigInt для сохранения точности.
• Рассмотрите возможность использования полифила: Если вам нужно поддерживать старые браузеры или среды выполнения, используйте пакет @js-temporal/polyfill.
• Тщательно тестируйте свой код: Проверяйте свой код с различными часовыми поясами и локалями, чтобы убедиться, что он корректно работает для всех пользователей.
• Документируйте свои предположения: Четко документируйте любые предположения, которые вы делаете о часовых поясах, локалях или форматах даты и времени.

Заключение

Temporal.Instant предоставляет надежный и точный способ представления моментов времени в JavaScript. Его неизменяемость, наносекундная точность и интеграция с другими типами Temporal делают его мощным инструментом для обработки сложных временных вычислений в различных приложениях. Понимая, как создавать, манипулировать и сравнивать объекты Instant, и следуя лучшим практикам интернационализации и обработки часовых поясов, вы сможете создавать надежную и точную функциональность для работы с датой и временем для глобальной аудитории. Использование Temporal API, включая объект Instant, позволяет разработчикам выйти за рамки ограничений устаревшего объекта Date и создавать более надежные и поддерживаемые приложения, которые точно отражают сложность времени в разных культурах и регионах.

По мере того как Temporal API получает все более широкое распространение, он готов стать стандартом для манипулирования датой и временем в JavaScript. Разработчики, которые ознакомятся с его возможностями и лучшими практиками, будут хорошо подготовлены к созданию следующего поколения приложений, учитывающих время.